From 060efc24ef1b6919c03d857eb11ed0209d51c884 Mon Sep 17 00:00:00 2001 From: Sam Reed Date: Sat, 28 May 2011 14:54:13 +0000 Subject: [PATCH] Loads more documentation for this file.. Hopefully CR will show it all ;) --- includes/parser/Preprocessor_DOM.php | 138 +++++++++++++++++++++++---- 1 file changed, 117 insertions(+), 21 deletions(-) diff --git a/includes/parser/Preprocessor_DOM.php b/includes/parser/Preprocessor_DOM.php index 9305496031..39c9edd7a2 100644 --- a/includes/parser/Preprocessor_DOM.php +++ b/includes/parser/Preprocessor_DOM.php @@ -10,7 +10,13 @@ * @ingroup Parser */ class Preprocessor_DOM implements Preprocessor { - var $parser, $memoryLimit; + + /** + * @var Parser + */ + var $parser; + + var $memoryLimit; const CACHE_VERSION = 1; @@ -42,6 +48,10 @@ class Preprocessor_DOM implements Preprocessor { return new PPCustomFrame_DOM( $this, $args ); } + /** + * @param $values + * @return PPNode_DOM + */ function newPartNodeArray( $values ) { //NOTE: DOM manipulation is slower than building & parsing XML! (or so Tim sais) $xml = ""; @@ -65,6 +75,10 @@ class Preprocessor_DOM implements Preprocessor { return $node; } + /** + * @throws MWException + * @return bool + */ function memCheck() { if ( $this->memoryLimit === false ) { return; @@ -97,7 +111,7 @@ class Preprocessor_DOM implements Preprocessor { * cache may be implemented at a later date which takes further advantage of these strict * dependency requirements. * - * @private + * @return PPNode_DOM */ function preprocessToObj( $text, $flags = 0 ) { wfProfileIn( __METHOD__ ); @@ -154,6 +168,11 @@ class Preprocessor_DOM implements Preprocessor { return $obj; } + /** + * @param $text string + * @param $flags int + * @return string + */ function preprocessToXml( $text, $flags = 0 ) { wfProfileIn( __METHOD__ ); $rules = array( @@ -430,9 +449,7 @@ class Preprocessor_DOM implements Preprocessor { $accum .= '' . htmlspecialchars( $inner ) . ''; } $accum .= $close . ''; - } - - elseif ( $found == 'line-start' ) { + } elseif ( $found == 'line-start' ) { // Is this the start of a heading? // Line break belongs before the heading element in any case if ( $fakeLineStart ) { @@ -460,9 +477,7 @@ class Preprocessor_DOM implements Preprocessor { extract( $flags ); $i += $count; } - } - - elseif ( $found == 'line-end' ) { + } elseif ( $found == 'line-end' ) { $piece = $stack->top; // A heading must be open, otherwise \n wouldn't have been in the search list assert( $piece->open == "\n" ); @@ -564,7 +579,7 @@ class Preprocessor_DOM implements Preprocessor { } } - if ($matchingCount <= 0) { + if ( $matchingCount <= 0 ) { # No matching element found in callback array # Output a literal closing brace and continue $accum .= htmlspecialchars( str_repeat( $curChar, $count ) ); @@ -614,7 +629,7 @@ class Preprocessor_DOM implements Preprocessor { $accum =& $stack->getAccum(); # Re-add the old stack element if it still has unmatched opening characters remaining - if ($matchingCount < $piece->count) { + if ( $matchingCount < $piece->count ) { $piece->parts = array( new PPDPart ); $piece->count -= $matchingCount; # do we still qualify for any callback with remaining count? @@ -637,16 +652,12 @@ class Preprocessor_DOM implements Preprocessor { # Add XML element to the enclosing accumulator $accum .= $element; - } - - elseif ( $found == 'pipe' ) { + } elseif ( $found == 'pipe' ) { $findEquals = true; // shortcut for getFlags() $stack->addPart(); $accum =& $stack->getAccum(); ++$i; - } - - elseif ( $found == 'equals' ) { + } elseif ( $found == 'equals' ) { $findEquals = false; // shortcut for getFlags() $stack->getCurrentPart()->eqpos = strlen( $accum ); $accum .= '='; @@ -672,7 +683,12 @@ class Preprocessor_DOM implements Preprocessor { * @ingroup Parser */ class PPDStack { - var $stack, $rootAccum, $top; + var $stack, $rootAccum; + + /** + * @var PPDStack + */ + var $top; var $out; var $elementClass = 'PPDStackElement'; @@ -685,6 +701,9 @@ class PPDStack { $this->accum =& $this->rootAccum; } + /** + * @return int + */ function count() { return count( $this->stack ); } @@ -733,6 +752,9 @@ class PPDStack { $this->accum =& $this->top->getAccum(); } + /** + * @return array + */ function getFlags() { if ( !count( $this->stack ) ) { return array( @@ -780,6 +802,9 @@ class PPDStackElement { return $this->parts[count($this->parts) - 1]; } + /** + * @return array + */ function getFlags() { $partCount = count( $this->parts ); $findPipe = $this->open != "\n" && $this->open != '['; @@ -792,6 +817,8 @@ class PPDStackElement { /** * Get the output string that would result if the close is not found. + * + * @return string */ function breakSyntax( $openingCount = false ) { if ( $this->open == "\n" ) { @@ -836,7 +863,21 @@ class PPDPart { * @ingroup Parser */ class PPFrame_DOM implements PPFrame { - var $preprocessor, $parser, $title; + + /** + * @var Preprocessor + */ + var $preprocessor; + + /** + * @var Parser + */ + var $parser; + + /** + * @var Title + */ + var $title; var $titleCache; /** @@ -854,7 +895,7 @@ class PPFrame_DOM implements PPFrame { /** * Construct a new preprocessor frame. - * @param $preprocessor Preprocessor: The parent preprocessor + * @param $preprocessor Preprocessor The parent preprocessor */ function __construct( $preprocessor ) { $this->preprocessor = $preprocessor; @@ -868,6 +909,8 @@ class PPFrame_DOM implements PPFrame { /** * Create a new child frame * $args is optionally a multi-root PPNode or array containing the template arguments + * + * @return PPTemplateFrame_DOM */ function newChild( $args = false, $title = false ) { $namedArgs = array(); @@ -903,6 +946,12 @@ class PPFrame_DOM implements PPFrame { return new PPTemplateFrame_DOM( $this->preprocessor, $this, $numberedArgs, $namedArgs, $title ); } + /** + * @throws MWException + * @param $root + * @param $flags int + * @return string + */ function expand( $root, $flags = 0 ) { static $expansionDepth = 0; if ( is_string( $root ) ) { @@ -1114,6 +1163,11 @@ class PPFrame_DOM implements PPFrame { return $outStack[0]; } + /** + * @param $sep + * @param $flags + * @return string + */ function implodeWithFlags( $sep, $flags /*, ... */ ) { $args = array_slice( func_get_args(), 2 ); @@ -1139,6 +1193,8 @@ class PPFrame_DOM implements PPFrame { /** * Implode with no flags specified * This previously called implodeWithFlags but has now been inlined to reduce stack depth + * + * @return string */ function implode( $sep /*, ... */ ) { $args = array_slice( func_get_args(), 1 ); @@ -1234,20 +1290,31 @@ class PPFrame_DOM implements PPFrame { } } + /** + * @return array + */ function getArguments() { return array(); } + /** + * @return array + */ function getNumberedArguments() { return array(); } + /** + * @return array + */ function getNamedArguments() { return array(); } /** * Returns true if there are no arguments in this frame + * + * @return bool */ function isEmpty() { return true; @@ -1259,6 +1326,8 @@ class PPFrame_DOM implements PPFrame { /** * Returns true if the infinite loop check is OK, false if a loop is detected + * + * @return bool */ function loopCheck( $title ) { return !isset( $this->loopCheckHash[$title->getPrefixedDBkey()] ); @@ -1266,6 +1335,8 @@ class PPFrame_DOM implements PPFrame { /** * Return true if the frame is a template frame + * + * @return bool */ function isTemplate() { return false; @@ -1277,9 +1348,21 @@ class PPFrame_DOM implements PPFrame { * @ingroup Parser */ class PPTemplateFrame_DOM extends PPFrame_DOM { - var $numberedArgs, $namedArgs, $parent; + var $numberedArgs, $namedArgs; + + /** + * @var PPFrame_DOM + */ + var $parent; var $numberedExpansionCache, $namedExpansionCache; + /** + * @param $preprocessor + * @param $parent PPFrame_DOM + * @param $numberedArgs array + * @param $namedArgs array + * @param $title Title + */ function __construct( $preprocessor, $parent = false, $numberedArgs = array(), $namedArgs = array(), $title = false ) { parent::__construct( $preprocessor ); @@ -1314,8 +1397,11 @@ class PPTemplateFrame_DOM extends PPFrame_DOM { $s .= '}'; return $s; } + /** * Returns true if there are no arguments in this frame + * + * @return bool */ function isEmpty() { return !count( $this->numberedArgs ) && !count( $this->namedArgs ); @@ -1380,6 +1466,8 @@ class PPTemplateFrame_DOM extends PPFrame_DOM { /** * Return true if the frame is a template frame + * + * @return bool */ function isTemplate() { return true; @@ -1414,6 +1502,9 @@ class PPCustomFrame_DOM extends PPFrame_DOM { return $s; } + /** + * @return bool + */ function isEmpty() { return !count( $this->args ); } @@ -1430,7 +1521,12 @@ class PPCustomFrame_DOM extends PPFrame_DOM { * @ingroup Parser */ class PPNode_DOM implements PPNode { - var $node, $xpath; + + /** + * @var DOMElement + */ + var $node; + var $xpath; function __construct( $node, $xpath = false ) { $this->node = $node; -- 2.20.1